Custom Functions

Custom / User-Defined Calculated Expressions

When creating a new calculated item SCS allows you to choose from a predefined set of canned functions or create your own custom expression. This choice cannot be changed once created. If you choose to create a custom expression then you can generate a very simple or extremely complex function to take whatever source data you want, manipulate it and output your desired results.

When ACQ outputs a calculated message it formats it similar to a NMEA string. This means it starts with a sentence label ($DERIV) followed by its comma delimited data with a line feed control character at the end.

It is recommended you use the Pre-Programmed functions if they meet your requirement instead of defining your own.

Integration with R and other external tooling has not been included in this release of SCS. You can only use the SCS expression builder and the limitations therein.

The Basic tab consists of the following fields:

Description
- Provide an optional description of this item.
System Name
- System generated name, read only format standard across all SCS systems.
- Useful for post-processing data on shore from multiple different sources/vessels.
- Useful for rotating personnel as each ship will always comply with this format.
- If you wish to have a more user friendly name you can edit the Display Name attribute below
Display Name
- User supplied name
- Can be anything you wish though must be unique.
Type
- The Type of Message Definition being defined.
- This is set upon creation and cannot be changed after the fact.
Log Messages
- A flag lettings ACQ know if this stream should be logged to disk (files / database) or not.
- If unchecked this data will still be available to all clients and calculated devices, but will not be stored on disk.
Enabled
- A flag letting SCS know if this interface is actively providing data or if it should be ignored by client applications such as ACQ.
Termination Characters
- The last character (often a control character) which signifies the end of the data string.
Sentence Label
- The value to insert as the first field in the output (read-only)
Calculation Parameters
- Allows you to specify the source data used when executing this calculation.
- Instead of calculating a result every second like in prior versions of SCS the current version allows you to specify one or more triggers. When data from a source marked as a trigger is obtained the calculation is executed. eg if you have a COG from a normal GPS coming in every second and set that as your source then the calculation will be 1x/second but if you have a COG from a POSMV coming in at 10x/second and set that as your source instead then the calculation will occur 10x/second.
- In custom definitions you can provide a 'friendly name' for each source field, this is the name of the variable you want to associate with this field when building out your custom equation.
Custom Equation
- The equation you want to execute when generating the output for this calculation (see below).

The Advanced tab consists of the following fields:

Comment
- A general comment pertaining to this item
Keywords
- Optional tags used to assist with text searches and metadata
Log Folder Path
- If Log Messages is enabled this specified an optional sub-folder for the RAW file containing the message's data
Delimiters
- The character(s) to use to split the message into its Data Fields - should be a comma, do not change this!
Relay via UDP Broadcast
- A flag which tells ACQ to immediately send the data out via UDP Broadcast the instant it is read from the interface.

Custom Equation Editor

The Custom Equation editor is where you supply the expression you wish to execute to take the source data and build your output data.

It is recommended you:

Determine the formula you wish to execute in order to be aware of the source data you will need.
Build Calculation Parameters for each source field and assign it a unique and descriptive Friendly Name
Start typing out your formula into the equation editor combining appropriate mathematical functions and the variables you defined in step 2.
Tailor your result data fields

For example, to convert a temperature from Celsius to Fahrenheit:

Determine the formula:

(0°C × 9/5) + 32 = 32°F

Build parameters:

Only need a single source data item, a data field with a temperature reading in units of Celsius.

Build Formula

The custom equation editor allows the user to enter an algebraic expression out of user-defined variable names and system-defined constants and mathematical functions. This pseudo-code is compiled by the ACQ Service to be a resultant derived data field value. The expression is entirely what would appear on the right side of the equals (=) sign. The expression must contain only a single line. The algebraic expressions allow for addition (+), subtraction (-), multiplication (*) and division (/), and follow the rules for order of operations. The user-defined variables names, or friendly names, are forced to be lowercase. The system-defined constants and functions are all uppercase. Given the friendly name variables and the provided functions and constants, the expression should otherwise follow the syntax the C# programming language.

As you start typing the editor will highlight and attempt to assist you with your equation. If you start typing the friendly name of one of your source fields it will display the list for you to choose from and highlight them in green. When you end a scope the parenthesis will be highlight in yellow showing you whats inside. Math functions will also be displayed for you to choose from, many are the standard set you would find in Microsoft Excel.

As another example, consider the following custom equation that calculates the air pressure at sea level, given a sensor at 10 m above sea level. The expression, which is already a pre-programmed function available in CFE, is only to illustrate that mathematical operators.

Tailor Output Data Fields

Once your equation is complete proceed to the automatically created data fields (the outputs) for this interface.